<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Numeric&lt;T&gt;</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="concepts.html" title="Type Requirements">
<link rel="prev" href="concepts.html" title="Type Requirements">
<link rel="next" href="integer.html" title="Integer&lt;T&gt;">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="concepts.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="integer.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.numeric"></a>Numeric&lt;T&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="numeric.html#safe_numerics.numeric.description">Description</a></span></dt>
<dt><span class="section"><a href="numeric.html#idm56709143600">Notation</a></span></dt>
<dt><span class="section"><a href="numeric.html#idm56709133680">Associated Types</a></span></dt>
<dt><span class="section"><a href="numeric.html#idm56709128608">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="numeric.html#idm56709032512">Models</a></span></dt>
<dt><span class="section"><a href="numeric.html#idm56709030832">Header</a></span></dt>
<dt><span class="section"><a href="numeric.html#idm56709028832">Note on Usage of <code class="computeroutput">std::numeric_limits</code></a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="safe_numerics.numeric.description"></a>Description</h4></div></div></div>
<p>A type is Numeric if it has the properties of a number.</p>
<p>More specifically, a type T is Numeric if there exists a
    specialization of <code class="computeroutput">std::numeric_limits&lt;T&gt;</code>. See the
    documentation for the standard library class <code class="computeroutput">numeric_limits</code>.
    The standard library includes such specializations for all the built-in
    numeric types. Note that this concept is distinct from the C++ standard
    library type traits <code class="computeroutput">is_integral</code> and
    <code class="computeroutput">is_arithmetic</code>. These latter fulfill the requirement of the
    concept Numeric. But there are types T which fulfill this concept for
    which <code class="computeroutput">is_arithmetic&lt;T&gt;::value == false</code>. For example see
    <code class="computeroutput">safe_signed_integer&lt;int&gt;</code>.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm56709143600"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><code class="computeroutput">T, U, V</code></td>
<td align="left">A type that is a model of a Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t, u</code></td>
<td align="left">An object of a type modeling a Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">OS, IS</code></td>
<td align="left">A type that is a model of an output or input stream</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">os, is</code></td>
<td align="left">An object of a type modeling output or input stream</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm56709133680"></a>Associated Types</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody><tr>
<td align="left"><code class="computeroutput">std::numeric_limits&lt;T&gt;</code></td>
<td align="left">The numeric_limits class template provides a C++ program
            with information about various properties of the implementation's
            representation of the arithmetic types. See C++ standard
            18.3.2.2.</td>
</tr></tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm56709128608"></a>Valid Expressions</h4></div></div></div>
<p>In addition to the expressions defined in <a href="http://www.sgi.com/tech/stl/Assignable.html" target="_top">Assignable</a> the
    following expressions must be valid. In the safe_numerics library, a type
    is considered Numeric if and only if it it has an entry in the
    std::numeric_limits table with the following members. Note that this is
    different from the the definition of std::is_arithmetic in that the later
    is required to support all valid expressions which Numeric does not
    require support for all these expressions but only requires that they be
    correctly implemented if they are defined. Also is_arithmetic is only
    defined for built in numeric types while Numeric applies to any user types
    which "look like" a number.</p>
<div class="table">
<a name="idm56709127104"></a><p class="title"><b>Table 1. General</b></p>
<div class="table-contents"><table class="table" summary="General">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Type</th>
<th align="left">Return Value</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">Numeric&lt;T&gt;</code></td>
<td align="left"><code class="computeroutput">true_type</code></td>
<td align="left">
<code class="computeroutput">true</code> or <code class="computeroutput">false</code>
</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">Numeric&lt;T&gt;()</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> or <code class="computeroutput">false</code>
</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">std::numeric_limits&lt;T&gt;::is_specialized</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left"><code class="computeroutput">true</code></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">std::numeric_limits&lt;T&gt;::is_integer</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> or <code class="computeroutput">false</code>
</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">std::numeric_limits&lt;T&gt;::is_signed</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> or <code class="computeroutput">false</code>
</td>
</tr>
</tbody>
</table></div>
</div>
<p><br class="table-break"></p>
<p>Any or all of the following unary operators MAY be defined. Any such
    defined operators shall implement the semantics as described below</p>
<div class="table">
<a name="idm56709104816"></a><p class="title"><b>Table 2. Unary Operators</b></p>
<div class="table-contents"><table class="table" summary="Unary Operators">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Type</th>
<th align="left">Semantics</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">-t</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">Invert sign</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">+t</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">unary plus - a no op</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t--</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">post decrement</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t++</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">post increment</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">--t</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">pre decrement</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">++t</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">pre increment</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>Any or all of the following binary operators MAY be defined. Any
    defined operators shall implement the semantics as described bellow</p>
<div class="table">
<a name="idm56709085280"></a><p class="title"><b>Table 3. Binary Operators</b></p>
<div class="table-contents"><table class="table" summary="Binary Operators">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Type</th>
<th align="left">Semantics</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">t - u</code></td>
<td align="left"><code class="computeroutput">V</code></td>
<td align="left">subtract u from t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t + u</code></td>
<td align="left"><code class="computeroutput">V</code></td>
<td align="left">add u to t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t * u</code></td>
<td align="left"><code class="computeroutput">V</code></td>
<td align="left">multiply t by u</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t / u</code></td>
<td align="left"><code class="computeroutput">T</code></td>
<td align="left">divide t by u</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t &lt; u</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> if t less than u, <code class="computeroutput">false</code>
            otherwise</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t &lt;= u</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> if t less than or equal to u,
            <code class="computeroutput">false</code> otherwise</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t &gt; u</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> if t greater than u, <code class="computeroutput">false</code>
            otherwise</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t &gt;= u</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> if t greater than or equal to u,
            <code class="computeroutput">false</code> otherwise</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t == u</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> if t equal to u, <code class="computeroutput">false</code>
            otherwise</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t != u</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">
<code class="computeroutput">true</code> if t not equal to u, <code class="computeroutput">false</code>
            otherwise</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t = u</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td>
<td align="left">assign value of u to t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t += u</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td>
<td align="left">add u to t and assign to t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t -= u</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td>
<td align="left">subtract u from t and assign to t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t *= u</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td>
<td align="left">multiply t by u and assign to t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t /= u</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td>
<td align="left">divide t by u and assign to t</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">os &lt;&lt; t</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">OS &amp;</code></code></td>
<td align="left">write contents of t to output stream</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">is &gt;&gt; t</code></td>
<td align="left"><code class="computeroutput"><code class="computeroutput">IS &amp;</code></code></td>
<td align="left">read contents of an input stream into t</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm56709032512"></a>Models</h4></div></div></div>
<p><code class="computeroutput">int, float, safe_signed_integer&lt;int&gt;,
    safe_signed_range&lt;int&gt;, checked_result&lt;int&gt;,
    etc.</code></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm56709030832"></a>Header</h4></div></div></div>
<p><a href="../../include/boost/safe_numerics/concept/numeric.hpp" target="_top"><code class="computeroutput">#include
    &lt;boost/safe_numerics/concepts/numeric.hpp&gt; </code></a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm56709028832"></a>Note on Usage of <code class="computeroutput">std::numeric_limits</code>
</h4></div></div></div>
<p>This in turn raises another question: Is it "legal" to specialize
    <code class="computeroutput">std::numeric_limits</code> for one's own types such as
    <code class="computeroutput">safe&lt;int&gt;</code>. In my view the standard is ambiguous on
    this. See various interpretations: </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><a href="https://stackoverflow.com/questions/16122912/is-it-ok-to-specialize-stdnumeric-limitst-for-user-defined-number-like-class" target="_top">is-it-ok-to-specialize-stdnumeric-limitst-for-user-defined-number-like-class</a></p></li>
<li class="listitem"><p><a href="https://en.cppreference.com/w/cpp/types/numeric_limits" target="_top">cppreference.com/w/cpp/types/numeric_limits</a></p></li>
</ul></div>
<p>In any case, it seems pretty clear that no harm will come of it. In
    spite of the consideration given to this issue, it turns out that the
    found no real need to implement these predicates. For example, there is no
    "is_numeric&lt;T&gt;" implemented as part of the safe numerics library.
    This may change in the future though. Even if not used, defining and
    maintaining these type requirements in this document has been very
    valuable in keeping the concepts and code more unified and
    understandable.</p>
<p>Remember that above considerations apply to other numeric types used
    in this library even though we don't explicitly repeat this information
    for every case.</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="concepts.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="integer.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
